Einheit 4 — Synology Chat

Was du nach dieser Einheit kannst: Einen Bot in Synology Chat anlegen, seine Nachrichten in einem 42°OS-Workflow empfangen, den Absender prüfen und über die Incoming-URL des Bots antworten.

Überblick


Art der Anbindung	Chatbot (Integration → Bots) für Einzelgespräche; Outgoing Webhook für Kanäle
Eingang	Synology Chat sendet jede Nachricht an den Bot per POST an die „Outgoing URL“
Echtheitsnachweis	Bot-Token im Feld `token` — keine Signatur
Antwort	POST an die „Incoming URL“ des Bots, Formularfeld `payload` mit JSON
Einrichtung	im Web-Client von Synology Chat (nicht in den Mobil-Apps)
Doku	Synology Chat — Integration · Webhooks und Slash-Befehle

Du brauchst: DSM 7 mit dem Paket Synology Chat Server, ein Konto mit Berechtigung für Integrationen, und ein NAS, das per HTTPS aus dem Internet erreichbar ist (für die Antworten, siehe Einheit 1).

Bot oder Webhook?

Ein Chatbot führt mit jeder Person ein eigenes Einzelgespräch — genau richtig für einen Assistenten. Soll der Workflow in einem Kanal auf Stichworte reagieren („#ticket …“), nimmst du stattdessen einen Outgoing Webhook. Beide liefern fast dieselben Felder; der Unterschied steht am Ende dieser Einheit.

Schritt 1 — Den Eingang in 42°OS anlegen

Lege einen Workflow Kanal | Synology Chat an und darin einen Webhook Agent syno_eingang:

Option	Wert
`secret`	lange Zufallszeichenkette
`verbs`	`post`
`payload_path`	`.`
`response`	`OK`
`code`	`200`
`ip_allowlist`	öffentliche IP-Adresse deines NAS

Speichere und kopiere die Webhook-URL.

Schritt 2 — Den Bot anlegen

Öffne Synology Chat im Browser.
Klicke auf dein Profilbild und wähle Integration.
Wechsle auf den Reiter Bots und klicke auf Erstellen.
Gib einen Namen (z. B. „Assistent“) und optional ein Bild an.
Trage bei Outgoing URL die Webhook-URL aus Schritt 1 ein. Ohne diese URL kann der Bot nichts empfangen — das Eingabefeld im Chat bleibt dann für Nutzer gesperrt.
Lass „Aus der Bot-Liste ausblenden“ ausgeschaltet, damit Nutzer den Bot selbst finden und anschreiben können.
Speichere. Öffne den Bot erneut und kopiere das Token und die Incoming URL.

Pro Chat-Server sind höchstens fünf Bots möglich.

Schritt 3 — Zugangsdaten hinterlegen

Lege in 42°OS zwei Credentials an:

Name	Inhalt
`synology_bot_token`	das Token des Bots
`synology_bot_url`	die vollständige Incoming URL, exakt so kopiert, wie DSM sie anzeigt

Incoming URL nicht nachbauen

Die Incoming URL hat die Form https://<nas>:<port>/webapi/entry.cgi?api=SYNO.Chat.External&method=…&version=2&token=%22…%22. Die %22 (Anführungszeichen um das Token) gehören dazu. Kopiere die URL immer aus dem Bot-Dialog, statt sie selbst zusammenzusetzen.

Schritt 4 — Nachrichten übersetzen

Synology Chat sendet die Nachricht als Formularfelder:

token=Ab3…&user_id=4&username=mmueller&post_id=1729384&timestamp=1730700000000&text=Wie+lief+der+Umsatz%3F

Feld	Bedeutung
`token`	Token des Bots — der Echtheitsnachweis
`user_id`	numerische ID der Person; brauchst du für die Antwort
`username`	Benutzername
`post_id`	ID der Nachricht
`timestamp`	Zeitpunkt in Millisekunden
`text`	der Text

Der Webhook Agent zerlegt die Formularfelder; im Log siehst du sie als Felder der Nachricht. Dahinter kommt der JavaScript Agent syno_uebersetzen:

Agent.receive = function() {
  var p = this.incomingMessage().payload || {};
  var b = p.web_request || p;
  // Echtheit: Token muss dem Bot-Token entsprechen
  var token = this.credential('synology_bot_token');
  if (!token || String(b.token || '') !== String(token)) { return; }

  var userId = String(b.user_id || '').replace(/[^0-9]/g, '');
  var postId = String(b.post_id || '').replace(/[^0-9]/g, '');
  var text = String(b.text || '').trim();
  if (!userId || !postId || !text) { return; }

  this.createMessage({
    kanal: 'synology',
    nachricht_id: 'syno-' + postId,
    unterhaltung_id: 'syno-' + userId,     // Einzelgespräch: eine Unterhaltung je Person
    absender_id: userId,
    absender_name: String(b.username || ''),
    text: text,
    datei: null,
    antwort_auf: postId
  });
};

Warum die User-ID in der Unterhaltungs-ID steckt

Ein Bot-Gespräch ist immer ein Einzelgespräch, und für die Antwort braucht Synology die User-ID. Steckt sie in der unterhaltung_id, findet der Ausgang den Empfänger ohne Nachschlagen — auch bei proaktiven Nachrichten.

Schritt 5 — Antworten senden

Synology erwartet die Antwort als Formularfeld payload, das ein JSON-Objekt enthält:

payload={"text":"Umsatz Oktober 2026: 84.200 €","user_ids":[4]}

Der JavaScript Agent syno_antwort baut dieses JSON:

Agent.receive = function() {
  var p = this.incomingMessage().payload || {};
  var text = String(p.antwort_text || '');
  var userId = parseInt(String(p.unterhaltung_id || '').replace('syno-', ''), 10);
  if (!text || !userId) { return; }
  // Markdown-Fettdruck entfernen, falls dein Chat ihn nicht darstellt
  text = text.replace(/\*\*(.+?)\*\*/g, '$1');
  this.createMessage({ syno_payload: JSON.stringify({ text: text, user_ids: [userId] }) });
};

Dahinter der Post Agent syno_senden:

Option	Wert
`post_url`	`{% credential synology_bot_url %}`
`method`	`post`
`content_type`	`form`
`payload`	`{"payload": "{{ syno_payload }}"}`
`emit_messages`	`true`
`emit_on_error`	`true`
`parse_response_json`	`true`

Synology antwortet mit {"success": true} — oder mit success: false und einem Fehlercode im Body.

Dateien senden

Statt Text kann die Antwort eine Datei enthalten: {"file_url": "https://…/bericht.pdf", "text": "Hier der Bericht", "user_ids": [4]}. Das NAS lädt die Datei selbst von dieser Adresse herunter (höchstens 32 MB). Die Adresse muss also vom NAS aus erreichbar sein.

Schritt 6 — Testen

Öffne in Synology Chat ein Gespräch mit dem Bot und schreib „Hallo“.
Prüfe die Logs von syno_eingang und syno_uebersetzen.
Verbinde testweise einen Echo-Agent (antwort_text: 'Echo: ' + p.text, die übrigen Felder unverändert übernehmen) mit syno_antwort. Die Antwort erscheint im Gespräch.

Für Kanäle: Outgoing Webhook

Soll der Workflow in einem Kanal reagieren:

Integration → Outgoing Webhooks → Erstellen: Kanal wählen (ohne Kanal: alle öffentlichen Kanäle), Auslösewörter festlegen (z. B. #ticket) und die Webhook-URL eintragen. Auslösewörter unterscheiden Groß- und Kleinschreibung.
Der Webhook liefert dieselben Felder wie der Bot und zusätzlich channel_id, channel_name und trigger_word. Prüfe im Eingang das Token des Webhooks und setze unterhaltung_id auf 'syno-k' + channel_id.
Für Antworten legst du unter Integration → Incoming Webhooks einen Webhook für diesen Kanal an und hinterlegst dessen URL als Credential. Die Antwort ist dann payload={"text":"…"} — ohne user_ids.

Häufige Stolpersteine

Antwort kommt nicht an, syno_senden meldet Verbindungsfehler. 42°OS erreicht das NAS nicht: Portfreigabe, Reverse Proxy und Zertifikat prüfen.
Zertifikatsfehler. Viele NAS laufen mit selbst signiertem Zertifikat. Richte in DSM ein Let's-Encrypt-Zertifikat ein.
Mehrere schnelle Antworten gehen verloren. Synology begrenzt die Rate pro URL. Schick lieber eine längere Nachricht als viele kurze; als Erfahrungswert hat sich etwa eine halbe Sekunde Abstand zwischen zwei Nachrichten bewährt.
Token im Klartext. Das Token steht im Body jeder Nachricht. Wer Zugriff auf Logs hat, sieht es. Begrenze den Zugang zu den Logs des Eingangs-Workflows.

Kurzer Selbst-Check

Warum prüft der Eingang das Token, obwohl die Webhook-URL schon geheim ist?

Weil beide Schutzmaßnahmen unterschiedliche Fälle abdecken: Die geheime URL schützt vor zufälligen Aufrufen, das Token beweist, dass die Nachricht wirklich von deinem Bot stammt. Wird die URL bekannt, schützt das Token weiter — und umgekehrt.

Überblick​

Schritt 1 — Den Eingang in 42°OS anlegen​

Schritt 2 — Den Bot anlegen​

Schritt 3 — Zugangsdaten hinterlegen​

Schritt 4 — Nachrichten übersetzen​

Schritt 5 — Antworten senden​

Dateien senden​

Schritt 6 — Testen​

Für Kanäle: Outgoing Webhook​

Häufige Stolpersteine​

Kurzer Selbst-Check​